/*
 * Copyright (C) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Image_NativeModule
 * @{
 *
 * @brief 提供图片处理的相关能力，包括图片编解码、从Native层获取图片数据等。\n
 * 
 * 使用该模块的接口，无需通过JS接口导入，可直接使用NDK完成功能开发。
 * @since 12
 */

/**
 * @file image_native.h
 *
 * @brief 声明图像的剪辑矩形、大小和组件数据的接口函数。
 *
 * @library libohimage.so
 * @kit ImageKit
 * @include <multimedia/image_framework/image/image_native.h>
 * @syscap SystemCapability.Multimedia.Image.Core
 * @since 12
 */

#ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_H
#define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_H

#include "image_common.h"
#include "native_buffer.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 为图像接口定义native层图像对象。
 *
 * @since 12
 */
struct OH_ImageNative;

/**
 * @brief 为图像接口定义native层图像对象的别名。\n
 * 此结构体内容不可直接操作，采用函数调用方式操作具体字段。\n
 * 释放OH_ImageNative对象使用{@link OH_ImageNative_Release}函数。
 *
 * @since 12
 */
typedef struct OH_ImageNative OH_ImageNative;

/**
 * @brief 获取Native {@link OH_ImageNative}对象的{@link Image_Size}信息。\n
 *
 * 如果OH_ImageNative对象所存储的是相机预览流数据，即YUV图像数据，那么获取到的Image_Size中的宽高分别对应YUV图像的宽高；
 * 如果OH_ImageNative对象所存储的是相机拍照流数据，即JPEG图像，由于已经是编码后的数据，Image_Size中的宽等于JPEG数据大小，高等于1。\n
 * OH_ImageNative对象所存储的数据是预览流还是拍照流，取决于应用将receiver中的surfaceId传给相机的previewOutput还是captureOutput。
 * 相机预览与拍照最佳实践请参考[预览流二次处理(C/C++)](../../media/camera/native-camera-preview-imageReceiver.md)与[拍照(C/C++)](../../media/camera/native-camera-shooting.md)。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param size 表示作为获取结果的Image_Size对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。\n
 *         IMAGE_UNKNOWN_ERROR：未知原因错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetImageSize(OH_ImageNative *image, Image_Size *size);

/**
 * @brief 获取Native {@link OH_ImageNative}对象的组件列表信息。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param types 表示作为获取结果的组件列表对象的指针。
 * @param typeSize 表示作为获取结果的组件列表中，元素个数的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetComponentTypes(OH_ImageNative *image,
    uint32_t **types, size_t *typeSize);

/**
 * @brief 获取Native {@link OH_ImageNative}对象中某个组件类型所对应的缓冲区。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param componentType 表示组件的类型。
 * @param nativeBuffer 表示作为获取结果的OH_NativeBuffer缓冲区对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetByteBuffer(OH_ImageNative *image,
    uint32_t componentType, OH_NativeBuffer **nativeBuffer);

/**
 * @brief 获取Native {@link OH_ImageNative}对象中某个组件类型所对应的缓冲区的大小。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param componentType 表示组件的类型。
 * @param size 表示作为获取结果的缓冲区大小的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetBufferSize(OH_ImageNative *image,
    uint32_t componentType, size_t *size);

/**
 * @brief 获取Native {@link OH_ImageNative}对象中某个组件类型所对应的像素行宽。\n
 *
 * 读取相机预览流数据时，需要考虑按stride进行读取，具体用法参考[预览流二次处理(C/C++)](../../media/camera/native-camera-preview-imageReceiver.md)。
 * 
 * @param image 表示OH_ImageNative native对象的指针。
 * @param componentType 表示组件的类型。
 * @param rowStride 表示作为获取结果的像素行宽的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetRowStride(OH_ImageNative *image,
    uint32_t componentType, int32_t *rowStride);

/**
 * @brief 获取Native {@link OH_ImageNative}对象中某个组件类型所对应的像素大小。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param componentType 表示组件的类型。
 * @param pixelStride 表示作为获取结果的像素大小的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetPixelStride(OH_ImageNative *image,
    uint32_t componentType, int32_t *pixelStride);
	
/**
 * @brief 获取Native {@link OH_ImageNative}对象中的时间戳信息。时间戳以纳秒为单位，通常是单调递增的。\n
 * 
 * 时间戳的具体含义和基准取决于图像的生产者，在相机预览/拍照场景，生产者就是相机。来自不同生产者的图像的时间戳可能有不同的含义和基准，因此可能无法进行比较。\n
 * 如果要获取某张照片的生成时间，可以通过{@link OH_ImageSourceNative_GetImageProperty}接口读取相关的EXIF信息。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @param timestamp 表示作为获取结果的时间戳信息的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_GetTimestamp(OH_ImageNative *image, int64_t *timestamp);

/**
 * @brief 释放Native {@link OH_ImageNative}对象。
 *
 * @param image 表示OH_ImageNative native对象的指针。
 * @return IMAGE_SUCCESS：执行成功。\n
 *         IMAGE_BAD_PARAMETER：参数错误。
 * @since 12
 */
Image_ErrorCode OH_ImageNative_Release(OH_ImageNative *image);

#ifdef __cplusplus
};
#endif
/** @} */
#endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_H
